'\" The contents of this file are subject to the AOLserver Public License
'\" Version 1.1 (the "License"); you may not use this file except in
'\" compliance with the License. You may obtain a copy of the License at
'\" http://aolserver.com/.
'\"
'\" Software distributed under the License is distributed on an "AS IS"
'\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
'\" the License for the specific language governing rights and limitations
'\" under the License.
'\"
'\" The Original Code is AOLserver Code and related documentation
'\" distributed by AOL.
'\" 
'\" The Initial Developer of the Original Code is America Online,
'\" Inc. Portions created by AOL are Copyright (C) 1999 America Online,
'\" Inc. All Rights Reserved.
'\"
'\" Alternatively, the contents of this file may be used under the terms
'\" of the GNU General Public License (the "GPL"), in which case the
'\" provisions of GPL are applicable instead of those above.  If you wish
'\" to allow use of your version of this file only under the terms of the
'\" GPL and not to allow others to use your version of this file under the
'\" License, indicate your decision by deleting the provisions above and
'\" replace them with the notice and other provisions required by the GPL.
'\" If you do not delete the provisions above, a recipient may use your
'\" version of this file under either the License or the GPL.
'\" 
'\"
'\" $Header$
'\"
'\" 
.so man.macros
.TH nt n 4.5 AOLserver "DCI Module"
.BS
.SH NAME
nt.debug, nt.dump, nt.exists, nt.get, nt.peek, nt.read, nt.send, nt.write \- Network tally commands
.SH SYNOPSIS
.nf
\fBnt.debug\fR ?\fIreset\fR?
\fBnt.dump\fR \fIbucket\fR (server)
\fBnt.exists\fR \fIbucket\fR (server)
\fBnt.get\fR \fIbucket\fR \fIproc\fR (server)
\fBnt.peek\fR \fIbucket\fR \fIproc\fR (server)
\fBnt.read\fR \fIfile\fR (server)
\fBnt.send\fR \fIbucket\fR \fIkey\fR \fIvalue\fR (client)
\fBnt.write\fR \fIfile\fR (server)
.fi
.BE

.SH DESCRIPTION
.PP
Network tally provides a simple mechanism for collecting counts from remote servers. Counts
are stored for user-defined keys, which belong to buckets. The basic model is that front-end 
clients update tally counts for keys within buckets, with the data processed by the back-end 
server. Client servers have configurable buffer which allows tally's to be collected even if 
the back-end server is not available. The back-end server stores data on disk for persistent 
storage across restarts. It's important to note, however, that the backup file is only written
at server exit in the case of a proper shutdown.
.PP
\fBnt.debug\fR (client, server) allows you to toggle debug messages on or off. 
.PP
\fBnt.dump\fR (server) returns a Tcl list of lists containing the keys, counts, and totals
for the specified \fIbucket\fR. Similiar to the \fBnt.peek\fR command, it does not zero
out any of the counts, or delete the bucket.
.PP
.CS
nt.dump views
{myPage 1 1} {myOtherPage 10 1}
.CE
.PP
\fBnt.send\fR (client) is used to send tally counts back to the tally server. 
\fIbucket\fR denotes the name of a bucket, which is simply a collection of key/value
pairs. \fIkey\fR specifies the name of the key that will hold the count. \fIvalue\fR is the 
integer amount to increment the count for a given key in a bucket by. Buckets and keys are self
initializing.
.PP
.CS
nt.send views myPage 1
nt.send views myOtherPage 10
.CE
.PP
\fBnt.exists\fR (server) returns 1 (true) or 0 (false) whether or not a specified
\fIbucket\fR exists.
.PP
.CS
nt.exists views
.CE
.PP
\fBnt.get\fR (server) allows you to get the current count (number of tally requests
received) and total (total amount tallied) for all keys in a given \fIbucket\fR. \fIproc\fR
is the name of the Tcl procedure to evaluate for each key. The callback must have the 
following arguments: \fIkey\fR, \fIcount\fR, and \fItotal\fR. Running this command will 
zero out all data and cause the specified bucket to be deleted.
.PP
.CS
proc tallyGetCallback {key count total} {
    ns_log notice "key: $key"
    ns_log notice "count: $count"
    ns_log notice "total: $total"
}

nt.get views tallyGetCallback
.CE
.PP
\fBnt.peek\fR (server) works exactly like the \fBnt.get\fR command above, however,
the data is not zeroed out and the bucket is not deleted.
.PP
\fBnt.read\fR (server) reads in a tally backup \fIfile\fR. Existing buckets, keys,
counts, and totals will either be overwriting or remain.
.PP
\fBnt.write\fR (server) writes a tally backup \fIfile\fR. Existing buckets, keys, 
counts, and totals will remain intact.  The format is a binary file with fixed-size
bucket and key name strings and network-byte order 32-bit unsigned integers.  The 
following Tcl script can be used to view a tally file:

.CS
#
# Tally backup file format:
#
# Header for each bucket:
#
#       bucket name:    16 byte, null terminated string
#       number of keys: 32 bit, unsigned integer in network byte order.
#
# Entry for each key:
#
#       key name:       32 byte, null terminated string
#       message count:  32 bit, unsigned integer in network byte order.
#       tally total:    32 bit, unsigned integer in network byte order.
#

set fp [open tally.bak]
fconfigure $fp -translation binary -encoding utf-8
while {[binary scan [read $fp 20] A16I buck nkeys] == 2} {
        puts "bucket: $buck, keys: $nkeys"
        for {set i 0} {$i < $nkeys} {incr i} {
                binary scan [read $fp 40] A32II key count total
                puts "  $key: $count $total"
        }
}
.CE

.SH CONFIGURATION (SERVER)
.CS
ns_section "ns/server/server1/module/nsdci/nt"
    ns_param debug

ns_section "ns/server/server1/module/nsdci/nt/server"
    ns_param backupfile tally.bak

ns_section "ns/server/server1/module/nsdci/nt/server/clients"
    ns_param gin gin.office.aol.com:5000
.CE
.SH CONFIGURATION (CLIENT)
.CS
ns_section "ns/server/server1/module/nsdci/rpc"
    ns_param debug 1
    ns_param port 5000
    ns_param address gin.office.aol.com

ns_section "ns/server/server1/module/nsdci/nt"
    ns_param debug

ns_section "ns/server/server1/module/nsdci/nt/client"
    ns_param max 1000
    ns_param timeout 5
.CE
.SH EXAMPLE
.CS
.CE

.SH KEYWORDS

.SH "SEE ALSO"
